From ac1c7a0680e21e7771f520d549d32dfb9e6eaa92 Mon Sep 17 00:00:00 2001 From: Tim Janik Date: Tue, 10 Oct 2006 14:40:50 +0000 Subject: [PATCH] applied patch from Michael Natterer to move to inline docs. applied Tue Oct 10 16:38:23 2006 Tim Janik * gtk/tmpl/gtkbindings.sgml: * gtk/gtkbindings.c: applied patch from Michael Natterer to move to inline docs. applied wording fixes suggested by Martyn Russell. --- ChangeLog | 6 ++ docs/reference/ChangeLog | 6 ++ docs/reference/gtk/tmpl/gtkbindings.sgml | 131 +---------------------- gtk/gtkbindings.c | 123 ++++++++++++++++++++- 4 files changed, 136 insertions(+), 130 deletions(-) diff --git a/ChangeLog b/ChangeLog index 80c37b3f09..6a68eb8cb7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +Tue Oct 10 16:38:23 2006 Tim Janik + + * gtk/tmpl/gtkbindings.sgml: + * gtk/gtkbindings.c: applied patch from Michael Natterer to move to + inline docs. applied wording fixes suggested by Martyn Russell. + 2006-10-09 Matthias Clasen * gdk/x11/gdkkeys-x11.c (gdk_keymap_translate_keyboard_state): diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 9caa396e7f..04273d7845 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +Tue Oct 10 16:38:23 2006 Tim Janik + + * gtk/tmpl/gtkbindings.sgml: + * gtk/gtkbindings.c: applied patch from Michael Natterer to move to + inline docs. applied wording fixes suggested by Martyn Russell. + Tue Oct 10 15:29:15 2006 Tim Janik * gtk/tmpl/gtkbindings.sgml: documented GtkBinding*, #358329. diff --git a/docs/reference/gtk/tmpl/gtkbindings.sgml b/docs/reference/gtk/tmpl/gtkbindings.sgml index e1f08faa8e..a5d9447df1 100644 --- a/docs/reference/gtk/tmpl/gtkbindings.sgml +++ b/docs/reference/gtk/tmpl/gtkbindings.sgml @@ -6,10 +6,10 @@ Key bindings for individual widgets -GtkBinding provide a mechanism for configuring Gtk+ key bindings through RC files. +GtkBinding provides a mechanism for configuring Gtk+ key bindings through RC files. This eases key binding adjustments for application developers as well as users and provides Gtk+ users or administrators with high key binding configurability which -require no application or toolkit side changes. +requires no application or toolkit side changes. @@ -68,7 +68,7 @@ The above example will not have the desired effect of causing "<Control>Ri and "<Control>Left" key presses to be ignored by Gtk+. Instead, it just causes any existing bindings from the bindings set "MoveCursor3" to be deleted, so when "<Control>Right" or "<Control>Left" are pressed, no binding for these keys -is found in binding set "MoveCursor3". Gtk+ will thusly continue to search for matching +is found in binding set "MoveCursor3". Gtk+ will thus continue to search for matching key bindings, and will eventually lookup and find the default Gtk+ bindings for entries which implement word movement. To keep Gtk+ from activating its default bindings, the "unbind" keyword can be used like this: @@ -164,48 +164,6 @@ key binding signal emission as stored in #GtkBindingSignal. @arg_type: implementation detail - - -Gtk+ maintains a global list of binding sets. Each binding set has a unique name -which needs to be specified upon creation. - - -@set_name: unique name of this binding set -@Returns: new binding set - - - - -This function returns the binding set named after the type name of the passed -in class structure. New binding sets are created on demand by this function. - - -@object_class: a valid #GtkObject class -@Returns: the binding set corresponding to @object_class - - - - -Find a binding set by its globally unique name. -The @set_name can either be a name used for gtk_binding_set_new() or the -type name of a class used in gtk_binding_set_by_class(). - - -@set_name: unique binding set name -@Returns: %NULL or the specified binding set - - - - -Find a key binding matching @keyval and @modifiers and activate the binding -on @object. - - -@object: object to activate when binding found -@keyval: key value of the binding -@modifiers: key modifier of the binding -@Returns: %TRUE if a binding was found and activated - @@ -217,90 +175,7 @@ on @object. @Returns: - - -Find a key binding matching @keyval and @modifiers within @binding_set - and activate the binding on @object. - - -@binding_set: the binding set to constrain the search to -@keyval: key value of the binding -@modifiers: key modifier of the binding -@object: object to activate when binding found -@Returns: %TRUE if a binding was found and activated - - Deprecated. - - - - - -Deprecated as public API, used only internally. - - -@binding_set: -@keyval: -@modifiers: - - - - -Override or install new key binding for @keyval with @modifiers on @binding_set. -When the binding is activated, @signal_name will be emitted on the target widget, -with @n_args @Varargs used as arguments. - - -@binding_set: @binding_set to install an entry for -@keyval: key value of binding to install -@modifiers: key modifier of binding to install -@signal_name: signal to execute upon activation -@n_args: number of arguments to @signal_name -@Varargs: arguments to @signal_name - - - - -This function is used internally by the GtkRC parsing mechanism to assign match -patterns to #GtkBindingSet structures. - - -@binding_set: binding set to add a path to -@path_type: path type the pattern applies to -@path_pattern: the actual match pattern -@priority: binding priority - - - - -Remove a binding previously installed via gtk_binding_entry_add_signal() on -@binding_set. - - -@binding_set: @binding_set to remove an entry of -@keyval: key value of binding to remove -@modifiers: key modifier of binding to remove - - - - -Deprecated. - - -@binding_set: binding set to add a signal to -@keyval: key value -@modifiers: key modifier -@signal_name: signal name to be bound -@binding_args: list of #GtkBindingArg signal arguments - - - - -Deprecated as public API, used only internally. - - -@scanner: GtkRC scanner -@Returns: expected token upon errors diff --git a/gtk/gtkbindings.c b/gtk/gtkbindings.c index 2d2786a960..c8f494790b 100644 --- a/gtk/gtkbindings.c +++ b/gtk/gtkbindings.c @@ -561,8 +561,17 @@ gtk_binding_entry_activate (GtkBindingEntry *entry, return handled; } +/** + * gtk_binding_set_new: + * @set_name: unique name of this binding set + * + * Gtk+ maintains a global list of binding sets. Each binding set has + * a unique name which needs to be specified upon creation. + * + * Return value: new binding set + **/ GtkBindingSet* -gtk_binding_set_new (const gchar *set_name) +gtk_binding_set_new (const gchar *set_name) { GtkBindingSet *binding_set; @@ -582,6 +591,16 @@ gtk_binding_set_new (const gchar *set_name) return binding_set; } +/** + * gtk_binding_set_by_class: + * @object_class: a valid #GtkObject class + * + * This function returns the binding set named after the type name of + * the passed in class structure. New binding sets are created on + * demand by this function. + * + * Return value: the binding set corresponding to @object_class + **/ GtkBindingSet* gtk_binding_set_by_class (gpointer object_class) { @@ -608,8 +627,18 @@ gtk_binding_set_by_class (gpointer object_class) return binding_set; } +/** + * gtk_binding_set_find: + * @set_name: unique binding set name + * + * Find a binding set by its globally unique name. The @set_name can + * either be a name used for gtk_binding_set_new() or the type name of + * a class used in gtk_binding_set_by_class(). + * + * Return value: %NULL or the specified binding set + **/ GtkBindingSet* -gtk_binding_set_find (const gchar *set_name) +gtk_binding_set_find (const gchar *set_name) { GSList *slist; @@ -626,6 +655,18 @@ gtk_binding_set_find (const gchar *set_name) return NULL; } +/** + * gtk_binding_set_activate: + * @binding_set: @binding_set to activate + * @keyval: key value of the binding + * @modifiers: key modifier of the binding + * @object: object to activate when binding found + * + * Find a key binding matching @keyval and @modifiers within + * @binding_set and activate the binding on @object. + * + * Return value: %TRUE if a binding was found and activated + **/ gboolean gtk_binding_set_activate (GtkBindingSet *binding_set, guint keyval, @@ -647,6 +688,14 @@ gtk_binding_set_activate (GtkBindingSet *binding_set, return FALSE; } +/** + * gtk_binding_entry_clear: + * @binding_set: + * @keyval: + * @modifiers: + * + * Use of this function is deprecated. + **/ void gtk_binding_entry_clear (GtkBindingSet *binding_set, guint keyval, @@ -666,6 +715,14 @@ gtk_binding_entry_clear (GtkBindingSet *binding_set, entry = binding_entry_new (binding_set, keyval, modifiers); } +/** + * gtk_binding_entry_skip: + * @binding_set: @binding_set to skip an entry of + * @keyval: key value of binding to skip + * @modifiers: key modifier of binding to skip + * + * Since: 2.12 + **/ void gtk_binding_entry_skip (GtkBindingSet *binding_set, guint keyval, @@ -686,6 +743,15 @@ gtk_binding_entry_skip (GtkBindingSet *binding_set, entry->marks_unbound = TRUE; } +/** + * gtk_binding_entry_remove: + * @binding_set: @binding_set to remove an entry of + * @keyval: key value of binding to remove + * @modifiers: key modifier of binding to remove + * + * Remove a binding previously installed via + * gtk_binding_entry_add_signal() on @binding_set. + **/ void gtk_binding_entry_remove (GtkBindingSet *binding_set, guint keyval, @@ -703,6 +769,16 @@ gtk_binding_entry_remove (GtkBindingSet *binding_set, binding_entry_destroy (entry); } +/** + * gtk_binding_entry_add_signall: + * @binding_set: binding set to add a signal to + * @keyval: key value + * @modifiers: key modifier + * @signal_name: signal name to be bound + * @binding_args: list of #GtkBindingArg signal arguments + * + * Deprecated. + **/ void gtk_binding_entry_add_signall (GtkBindingSet *binding_set, guint keyval, @@ -793,6 +869,20 @@ _gtk_binding_entry_add_signall (GtkBindingSet *binding_set, *signal_p = signal; } +/** + * gtk_binding_entry_add_signal: + * @binding_set: @binding_set to install an entry for + * @keyval: key value of binding to install + * @modifiers: key modifier of binding to install + * @signal_name: signal to execute upon activation + * @n_args: number of arguments to @signal_name + * @: arguments to @signal_name + * + * Override or install a new key binding for @keyval with @modifiers on + * @binding_set. When the binding is activated, @signal_name will be + * emitted on the target widget, with @n_args @Varargs used as + * arguments. + **/ void gtk_binding_entry_add_signal (GtkBindingSet *binding_set, guint keyval, @@ -879,6 +969,16 @@ gtk_binding_entry_add_signal (GtkBindingSet *binding_set, g_slist_free (free_slist); } +/** + * gtk_binding_set_add_path: + * @binding_set: binding set to add a path to + * @path_type: path type the pattern applies to + * @path_pattern: the actual match pattern + * @priority: binding priority + * + * This function is used internally by the GtkRC parsing mechanism to + * assign match patterns to #GtkBindingSet structures. + **/ void gtk_binding_set_add_path (GtkBindingSet *binding_set, GtkPathType path_type, @@ -1159,6 +1259,17 @@ gtk_bindings_activate_list (GtkObject *object, return handled; } +/** + * gtk_bindings_activate: + * @object: object to activate when binding found + * @keyval: key value of the binding + * @modifiers: key modifier of the binding + * + * Find a key binding matching @keyval and @modifiers and activate the + * binding on @object. + * + * Return value: %TRUE if a binding was found and activated + **/ gboolean gtk_bindings_activate (GtkObject *object, guint keyval, @@ -1451,6 +1562,14 @@ gtk_binding_parse_bind (GScanner *scanner, return G_TOKEN_NONE; } +/** + * gtk_binding_parse_binding: + * @scanner: GtkRC scanner + * + * Deprecated as public API, used only internally. + * + * Return value: expected token upon errors, %G_TOKEN_NONE on success. + **/ guint gtk_binding_parse_binding (GScanner *scanner) { -- 2.30.2